Beyond the Classic Editor:Advanced Wiki Editing
Habitica's wiki is an ever-changing set of articles to help all players find updated information quickly and easily. Wiki editors have the goal of explaining and presenting information as clearly as possible. There are many tools available to wiki editors other than what's available in the classic editor and this is a guide to provide navigation and instruction on those tools. To talk about the tools, it is easier to present them grouped with the events for which wiki editors need to provide updated information such as new quests, new features, Mystery Items, backgrounds, and Grand Galas. Spoilers By using many of these tools, you will be able to preview upcoming content. Beware of spoilers if you do not want the surprise of new content to be ruined for you! Wiki editors should not add any content (articles or pictures) about upcoming features to the wiki prior to their official release in the game. There are three main reasons for this: *The content may change before its official release. *Documenting new features early has in the past spoiled the surprise for readers, so we are careful to be respectful of their playing experience. *Features may take some time to release, but coders may upload partially completed code changes for their own testing purposes. A feature is not considered released until it appears in a Bailey announcement. For events with multiple parts (for example, The Abominable Stressbeast had several phases that were released over the course of several weeks), only reveal the publically announced part. Shortcuts Subsequent sections give detailed information on finding code in the GitHub repository. This is a table of shortcuts to the code. Each shortcut is also available in the section in which it's explained. General Notes Broad v. Slim Armor There are two versions of armor: broad (e.g., broad_armor_special_spring2015Healer.png) and slim (e.g., slim_armor_special_spring2015Healer.png). Only the broad version needs to be uploaded to the wiki (the Equipment Table Creator uses the broad version, and the two versions are similar enough that they don't need to both be uploaded). Quests Previewing Quests All new quest ideas are logged on the Quests Trello. There are columns for Equipment Quests, Pet Quests, and future quest types which are in development stages. Storytellers submit ideas for questlines and rewards on these Trello cards. Additionally, the pixel art for these quests is logged on the Pixel Art Trello. Relating to quests, there are columns for Pet Quests, Boss Quests, and Promotional Art New Quests Once a quest has been finalized and is ready for implementation in the game, its aspects (pixel art, text, rewards) are coded into the Habitica game. All active code can be seen in the GitHub repository, `develop` branch. It is safe to look at the code and copy parts of it for use in wiki articles. Remember, DO NOT DOCUMENT UNRELEASED CONTENT. Sometimes a quest will appear in GitHub for testing purposes, but has not yet been completed or finalized; quests have been known to change between the initial testing phase and the final released version or are sometimes uploaded with incomplete graphic sets. It can also confuse people to see Wiki content describing items and quests that are not yet available. Finding Quest Text The actual text of the quest can be found in the `common` directory, then in the `locales` sub-directory. Here you'll find translations for different languages. For this example, we'll choose `en` for English. Then choose `questsContent.json` Shortcut: Quest Text You can either click `History` to see the latest changes, or you can use the search function and enter a keyword in the quest name. Each quest has identifiers found in the code. We'll use The Jelly Regent quest as an example with the keyword "Slime". Finding Rewards To find the dropped rewards for the quests, start with the `common` directory, then choose the `script` sub-directory, then `content`, then `index.js`. You can click `History` to see the latest changes in the code or you can search for the quest keyword. Shortcut: Quest Rewards For example, for The Jelly Regent, search for the keyword `slime`. Under `drop`, we find the following pieces of information: items: [ { type: 'eggs', key: 'Slime', text: t('questSlimeDropSlimeEgg') }, { type: 'eggs', key: 'Slime', text: t('questSlimeDropSlimeEgg') }, { type: 'eggs', key: 'Slime', text: t('questSlimeDropSlimeEgg') } ], This indicates that three slime eggs are dropped as quest rewards. gp: 31, This indicates that the quest rewards 31 GP upon completion. exp: 200, This indicates that the quest rewards 200 XP upon completion. Finding Promotional Art Some of the quests have more expansive promotional art. This can be found on the Pixel Art Trello on the column "Promotional Art". Clicking the card will open the page where you can see attachments loaded. These can be downloaded to your computer, then uploaded to the wiki for use in the quest articles. Finding Quest Pictures Each quest has pixel art for the boss, quest scroll, egg, pets, and mounts. These can be found by going to website > assets > sprites > spritesmith > quests. Shortcut: Quest Pictures The boss pictures and quest scrolls can be found in the folders "bosses" and "scrolls". Items for collection quests are found in the "items" folder. The eggs, pets, and mounts can be found in website > assets > sprites > spritesmith > stable. For any picture file, click it to open the picture, Then download to your computer and upload to the wiki for use in the quest articles. Assembling Mount Pictures Each mount is created from two images: one for the head and one for the body. Only the head is displayed in the Stable in the game to save space. The heads and bodies are joined when a mount is used in your avatar. The naming convention for the files in GitHub indicates body or head, mount type, and color: Mount_Body_''Name''-''Style''.png and Mount_Head_''Name''-''Style''.png For example, Mount_Body_Octopus-Zombie.png and Mount_Head_Octopus-Zombie.png Download both the body and the head to your computer. To assemble the mounts for use in the wiki, use any photo editor. GIMP is a popular freeware editor. SumoPaint is another free online photo editor. In the photo editor, use the selection to open as layers, starting with the body picture first. Then using open as layers, select the head picture. It should overlay on the body picture, leaving a transparent background. Save or export this assembled picture as a PNG file to preserve the transparency. The file name convention to use is Mount_Octopus-Zombie.png. Note that the first punctuation mark is an underscore and the second is a hyphen - use this convention for any new files you upload. Checklist for New Pet Quests A new pet quest is released each month, and several wiki updates need to be made each time. This is a list of the edits that typically need to be made when a new pet quest is released: *Image Uploads: **Pet in all colors **Mount in all colors (must be assembled as described above) **Egg **Quest scroll **Boss **Promotional art, if any *Create new quest page (copy-paste source code from a similar quest page and change details as necessary; be sure not to copy the interlanguage links) *Add new page to Index *Add new quest info to: **Quests **Template:Quest Table Easy, Template:Quest Table Medium, or Template:Quest Table Hard. Follow the instructions at the top of the template page to use the Quest Table Creator. **Pets **Mounts **Eggs **Boss **Art Credits **Script Credits **Characters in Habitica#Habiteer Cameos **Places in Habitica, if applicable Backgrounds Each month three new backgrounds are released. These are filed in habitrpg > website > assets > sprites > spritesmith > backgrounds. The background files are listed in alphabetical order with the addition dates in the far right column. Shortcut: Backgrounds Make sure to update both the Backgrounds and Art Credits pages. Testing A Sandbox is a page that can be used to practice editing, to learn the formatting, and to put together drafts without necessarily publishing it to the main page. If you are someone who learns by doing, having a sandbox where you can try out code, formatting, and design can be very useful. For a step-by-step guide on creating your user sandbox, see Guidance for Scribes. Templates Templates are wiki pages that include reusable snippets of code or text. These can be inserted into any page. The benefit of templates is they only have to be edited once in order to change the wording or code on any page where they are placed. *Template category page: A full list of templates is available on the template category page. *General wiki templates: A list of templates that came with the wiki. * : Basic and more advanced usage, customization, and creation of templates. Templates are created with the preface `Template:` followed by the page name. You can edit them like any normal wiki page. `Template:Example`. They are inserted into a wiki page using beginning double brackets, the template name, then closing double brackets. Testing Templates To create a trial template, you can use your sandbox that was discussed earlier. Use the syntax `/Sandbox/Template:Example Name` and publish it. To use the trial template in a trial wiki page in your sandbox, insert it using Grand Galas Grand Galas are the Habitica seasonal events that happen quarterly. They typically involve special class gear and items. Finding Pictures The Grand Gala class gear pixel art can be found in the GitHub repository starting in website > assets > sprites > spritesmith > gear > events > then the season: fall, winter, spring, or summer. Shortcut: Grand Galas Gear Pictures Each class will have up to five pieces of seasonal gear. The file names will include the identifiers for the gear, class, and year. Finding Text Each piece of special class gear has a name, caption, cost, and boost to the player's stats. These can be found in the code. Shortcut: Grand Galas Gear Text The name and caption can be found in common > locales > en > gear.json. Each piece of gear will have a placeholder such as armorSpecialSpring2015RogueText which is the name of the item. The placeholder such as armorSpecialSpring2015RogueNotes will be the caption. To find the cost and stats boost, go to common > script > content > gear > sets > special > index.js. You can use "History" to select the commit that shows the event that was added. Then you will need to search for the event and year (it's easiest to do this using the Ctrl-F keyboard shortcut). The code is grouped by gear type, then class. For instance, weapon is first in the code with the information for all four classes listed. The lines weaponSpecialSpring2015RogueNotes', {str: 8}), value: 80, str: 8, show that the Rogue weapon gives an 8 increase to Strength and costs 80 gold. weaponSpecialSpring2015MageNotes', {int: 15, per: 7}), value: 160, int:15, per:7, shows that the Mage weapon gives both an increase to Intelligence by 15 and to Perception by 7 and costs 160 gold. Of special note is that the Mage has a two handed weapon (no shield item will be shown in the list), and the Rogue's off-hand weapon is considered a shield and may be grouped with the shields. Assembling Class Gear Template Class gear explanatory templates are used on the Grand Galas pages to summarize the gear and its benefits. The template pages are typically named using the class gear set name and can include the class (for example: Mage Magicians Bunny or Emerald Mermages. Other Grand Gala Elements *Achievements: If the Grand Gala has an associated achievement, such as Agricultural Friends during Spring Fling, the achievement badges can be found in common > img > sprites > spritesmith > achievements. *Misc: If there is a special buff (such as Shiny Seed during Spring Fling) or card (such as New Year's Card), these images will be placed in website > assets > sprites > spritesmith > misc. *NPC Changes: If the NPC's change clothing, they're filed in website > assets > sprites > spritesmith > npcs. *Seasonal Shop: If there are new items for sale in the Seasonal Shop, they're listed in website > assets > sprites > spritesmith > shop. *Customizations: Hair and skin customizations are stored in website > assets > sprites > spritesmith > customize, under their appropriate folder: beards, chairs, flowers, hair, shirts, or skin. Mystery Items Subscribers receive monthly Mystery Items. These are filed in website > assets > sprites > spritesmith > gear > events. Each Mystery Item will have the month and year in its file name. Shortcut: Mystery Items To see promotional pixel art for the Mystery Items, such as an avatar wearing the gear, go to sprites > spritesmith_large > promo. Each file will have the prefix `promo_mystery`, followed by the month and year. Shortcut: Promo Art The name and captions for the Mystery Items are found in the code in habitrpg > website > common > locales > en > gear.json. You can click `History` to see the latest changes in the code or you can search for `Mystery`, `year`, `month`. For example, the Mystery Item files for April 2015 can be searched using `Mystery201504`. Shortcut: Mystery Item text Enchanted Armoire New equipment is released monthly for the Enchanted Armoire. The pictures are filed in habitrpg > website > assets > sprites > spritesmith > gear > armoire. The individual images have descriptive titles (rather than dates released), so the easiest way to find the latest additions is to look at the latest commit (in the right-hand corner above the right column). Shortcut: Enchanted Armoire Gear The Enchanted Armoire table is built using the Template:Enchanted_Armoire_Table_Code which gives instructions on running the table creator. Features Since Habitica is an open source program, many programmers contribute by adding requested features and fixing bugs. They start by setting up a local install of Habitica on their computers for development and testing. Wiki editors will need to understand how the new features work so they can describe them accurately to readers. New Features When programmers are making some changes and are happy with their code so far, they will make a permanent store of those changes by creating a "commit" on their local computer. When the entire set of changes to fix a bug or build a feature has been finished (that might be one commit or many), they will submit all of the commit(s) to be reviewed in a "pull request" to GitHub. This makes the commits visible in GitHub. In theory, the names given to the commits and to the pull request should accurately describe what is in them, so you can often find a specific code change like that. For example, on the second page of commits, you will see one called "feat(customize): Spring Colors" by SabreCat. Pull Requests The list of latest pull requests can be found at GitHub and clicking `Pull Requests` in the right-hand column. There should be a number indicating how many are available to view, usually around 40. All of the pull requests, their statuses, and how many comments are attached are listed. Shortcut: Pull Requests Commits The list of latest commits can be found at GitHub and clicking `Commits` in the row with the red, yellow, and blue bars. There should be a number indicating how many are available to view, somewhere around 9000. Shortcut: Commits The commits are grouped by date and each has a brief description. Clicking the commit will show you more information about the function of the feature (supplied by the programmer) plus which files were changed. Bugs Bugs or software glitches are also tracked in the GitHub repository. Users will open an issue by clicking `Issues` in the right-hand column. This will give a listing of open issues. A user can click the green `New Issue` button to log the software problem they encountered. Shortcut: Issues Programmers and developers read, comment, and work on these issues. Testing Code Moderator Alys prepared this explanation of how code is tested on the beta.habitrpg.com beta.habitrpg.com site in response to a question about it. GitHub has the concept of "branches". A branch is a complete copy of the website 1 but with certain differences, such as new code to fix a bug or create a new feature. There can be multiple branches in a repository, with each one being used to work on a different feature. In our GitHub repository, the main branch is called `develop` and it is the same as the production website but with a few extra pieces of new code that have been recently approved and will go live within a few days. When `develop` is made live we usually deploy 2 it to both production 3 and beta at the same time, just to keep the two sites in sync. If `develop` contains very big or important changes (e.g., a new Grand Gala) we will often deploy it to beta first, test it for a few minutes or a few hours (depending on the changes), and then deploy it to the main site. However, sometimes the beta site is used differently. There might be a large body of new code being written that will be significantly different than the current production site and that will take many days or weeks to create and test. 4 That code will be in a different GitHub branch 5, which means that it can be changed without affecting anything in the `develop` branch. When the code is at a stage that is suitable for at least some testing to be done, it is deployed to the beta site, and then the beta site is not used for anything else until the testing is finished 6. When we're happy with the new code, we will merge it into `develop` and then deploy it to production. 7 Footnotes: 1 Or a complete copy of a program's source code or of whatever is being maintained in GitHub. 2 Deploy means copy, usually with the implication that something is being copied from a development or testing environment to the "live" or "real" environment; I'm not sure how common that usage of "deploy" is outside of IT. 3 "production" is https://habitrpg.com/ 4 E.g., at the moment we are redesigning almost all of the skills to make them more balanced (some stronger, some weaker). 5 But in the same repository. A repository is a collection of branches, issues (bug reports), pull requests and commits (new features or bug fixes), documentation, etc. Basically, it's everything involved with an entire website (or an entire program). Habitica has one repository called habitrpg for the website (with many branches in it), and another repository called habitrpg-mobile for the mobile app. 6 Although if there is an urgent reason to do some short-term testing for another feature, we will temporarily overwrite beta with `develop` or another branch, but then soon re-deploy the long-term project's branch to beta. 7 One of the great benefits of GitHub (and git, the program that GitHub is based on) is that it makes merging two branches together incredibly easy, even if the branches have very different code in them. Git has some extremely advanced logic that allows it to recognize how two versions of one file should be combined into a single version. In many cases, it will correctly work out for itself which pieces of one file should override which pieces the other, and when it can't work that out (because there is a "conflict" between two pieces), it puts both pieces into one file but clearly marks them as being a conflict, so that a human can sort out what should be done. It doesn't let you proceed further in the merging/committing/deploying process until all conflicts have been handled (that's a useful safety feature). I love git. :) Wiki Help There are many ways to present useful content in the wiki and there are guides with examples to help editors. * Help:Designing your wikia is a page listing features that would be available for our Habitica wiki. Each link gives examples for coding and usage. The forum is also a great place for asking coding questions. Knowledgeable editors will usually reply quickly with answers. * MediaWiki offers even more extensive help. Using the Search bar can help you quickly find user examples and discussion about tools or features you're trying to find. Most Common Tools The following links are provided for the most commonly used tools. You can view the code, see examples, and copy and paste the code to add to the page you are editing. *Tabber which is used to add multiple tabs to a section of content, which can be toggled without having to reload the page. *Tables help organize your pages to display data, facts, and other information. *Infoboxes are like fact sheets, or sidebars in magazine articles, designed to present a summary of the topic of the page. *Collapsing is a feature to collapse any element and is used to help conserve space on the page or to hide spoiler content. *Table of Contents can be displayed in many ways, depending on the page's intent. * are used to forward the user to a new page. Wiki Toolbar If you have a wiki account, you can utilize the toolbar that is at the bottom of your screen to use shortcuts and other tools to do various functions. You can find more info on the toolbar . For a list of available toolbar tools see this . Category:Contributing